QuickTime 3 Reference
Video output components provide functions for configuring the video display, for starting and stopping video output, and for specifying the graphics world used for the display. This section describes these functions.
To display a dialog box in which the user can specify video settings, call the QTVideoOutputGetConfigureDisplay function.
To get a pointer to the graphics world used by the video output component, call the QTVideoOutputGetGWorld function.
To obtain exclusive access to the video hardware controlled by a video output component, call the QTVideoOutputBegin function.
To release access to the video hardware controlled by a video output component, call the QTVideoOutputEnd function.
To get the name of the software, if any, that has exclusive access to the video hardware controlled by a video output component, call the QTVideoOutputGetCurrentClientName function.
If a video output device can display video both on an external video display and in a window on a computer's desktop, you can use the QTVideoOutputSetEchoPort function to specify a window on the desktop in which to display video sent to the device.
You use the QTVideoOutputBegin function in your software to obtain exclusive access to the video hardware controlled by a video output component.
pascal ComponentResult QTVideoOutputBegin (QTVideoOutputComponent vo);
vo Specifies the instance of a video output component. Your software obtains this reference when calling the Component Manager's OpenComponent or OpenDefaultComponent function.
When your software calls QTVideoOutputBegin, the video output component does the following:
If the video hardware is available, the video output component also
If the video output component supports the QTVideoOutputCustomConfigureDisplayfunction QTVideoOutputCustomConfigureDisplay , your software can call the function to display a custom video configuration dialog box.
When your software no longer needs the video output component, release it by calling the QTVideoOutputEnd function.
If the QTVideoOutputBegin function returns the videoOutputInUseErr result code that indicates that the video hardware is currently in use, your software can get the name of the application or other software that is using the hardware by calling the QTVideoOutputGetCurrentClientName function QTVideoOutputGetCurrentClientName . You can then display an alert to the user that
If your software needs to change the display mode, it must change it before calling QTVideoOutputBegin . It cannot change the display mode between calls to QTVideoOutputBegin and QTVideoOutputEnd .
If a video output component supports the optional QTVideoOutputCustomConfigureDisplay function, your software can call the function to display a custom video configuration dialog box. This dialog box can include settings that are specific to the video device controlled by the video output component.
pascal ComponentResult QTVideoOutputCustomConfigureDisplay (
QTVideoOutputComponent vo,
ModalFilterUPP filter);
vo Specifies the instance of a video output component for this request. Your software obtains this reference when calling the Component Manager's OpenComponent or OpenDefaultComponent function.
filter Specifies a Dialog Manager filter procedure for the video output component to use for the dialog box. The filter allows the software to process events while the dialog boxis displayed.
You use the QTVideoOutputEnd function in your software to release access to the video hardware controlled by a video output component.
pascal ComponentResult QTVideoOutputEnd (QTVideoOutputComponent vo);
vo Specifies the instance of a video output component. Your software obtains this reference when calling the Component Manager's OpenComponent or OpenDefaultComponent function.
Your software should release access to a video output component as soon as it is done using the video hardware controlled by the component.
If you close the instance of a video output component that currently has exclusive access to video hardware, the video output component automatically calls QTVideoOutputEnd to release the hardware.
You can use the QTVideoOutputGetCurrentClientName function in your software to get the name of the software, if any, that has exclusive access to the video hardware controlled by a video output component.
pascal ComponentResult QTVideoOutputGetCurrentClientName
(QTVideoOutputComponent vo, Str255 str);
vo Specifies the instance of a video output component for this request. Your software obtains this reference when calling the Component Manager's OpenComponent or OpenDefaultComponent function.
str The name of the software that has exclusive access to the video hardware controlled by a video output component, or a zero-length string if no software currently has access.
You use the QTVideoOutputGetGWorld function in your software to get a pointer to the graphics world used by a video output component.
pascal ComponentResult QTVideoOutputGetGWorld (
QTVideoOutputComponent vo,
GWorldPtr *gw);
vo Specifies the instance of a video output component for this request. Your software obtains this reference when calling the Component Manager's OpenComponent or OpenDefaultComponent function.
gw Contains a pointer to the graphics world used by the video output component to display images.
If the pixel format of the graphics world is 1, 2, 4, 8, 16, or 32, your software can use either QuickDraw or QuickTime to draw graphics to it. If the graphics world has any other pixel format, your software must use QuickTime functions draw to it.
Your software can pass the pointer returned by the QTVideoOutputGetGWorld function to the SetMovieGWorld , DecompressSequenceBegin , DecompressSequenceBeginS , DecompressImage , and FDecompressImage functions or, for Microsoft Windows, the equivalent functions described in Introduction to QuickTime 3 for Windows Programmers.
Your software can call QTVideoOutputGetGWorld only between calls to QTVideoOutputBegin and QTVideoOutputEnd . When your software calls QTVideoOutputEnd , the video output component automatically disposes of the graphics world. If your software needs to use the graphics world after calling QTVideoOutputEnd , it must call QTVideoOutputGetGWorld function again after the next time it calls QTVideoOutputBegin .
Your software must not call DisposeGWorld to dispose of the graphics world used by a video output component. The video output component automatically disposes of the graphics world when your software calls QTVideoOutputEnd .
A video output components's QTVideoOutputGetGWorldParameters function is called by the base video output component as part of its implementation of the QTVideoOutputGetGWorld function. QTVideoOutputGetGWorldParameters is not called by applications or other client software.
pascal ComponentResult QTVideoOutputGetGWorldParameters (
QTVideoOutputComponent vo,
Ptr *baseAddr,
long *rowBytes,
CTabHandle *colorTable);
vo Specifies an instance of your video output component.
baseAddr Contains the address at which to display pixels. If your video output component does not display pixels, return 0 for this parameter.
rowBytes Specifies the width of each scan line in bytes. If your video output component does not display pixels, return the width of the current display mode.
CTabHandle Identifies the color table to be used. If your video output component does not use a color table, return nil .
If a video output device can display video both on an external video display and in a window on a computer's desktop, you can use the QTVideoOutputSetEchoPort function to specify a window on the desktop in which to display video sent to the device. When your software sends video to the window you specify, the video is both displayed in the window and sent to the normal output of the video output device.
pascal ComponentResult QTVideoOutputSetEchoPort (
QTVideoOutputComponent vo,
CGrafPtr echoPort);
vo Specifies the instance of a video output component for this request. Your software obtains this reference when calling the Component Manager's OpenComponent or OpenDefaultComponent function.
echoPort Specifies the window on the computer's desktop in which to display the video.